Skip to content

FEAT: add unknown state to Parity - #397

Draft
Flomber wants to merge 3 commits into
mainfrom
unknown-parity
Draft

Flomber wants to merge 3 commits into
mainfrom
unknown-parity

Conversation

@Flomber

@Flomber Flomber commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Closes #19

✨ New features

  • Parity can now represent a parity that exists but whose value is not known, through the new Parity.UNKNOWN constant. This is distinct from None, which still means that a parity (such as C-parity or G-parity) is not defined for a particle at all. A new Parity.is_unknown property checks for this state.
  • Parity.UNKNOWN behaves consistently with known parities: negation leaves it unchanged, it survives copy, deepcopy, and pickle, it is hashable, and its repr is Parity.UNKNOWN. It sorts between None and Parity(-1), while int(Parity.UNKNOWN) and comparisons with plain integers raise a ValueError instead of silently treating the unknown value as a number.
  • Particle definition files can specify an unknown parity as {"value": "?"}. The particle validation schema accepts it, and qrules.io writes Parity.UNKNOWN in that form, so unknown parities round-trip through YAML and JSON.

⚙️ Enhancements

  • load_pdg() now distinguishes unknown from undefined parities for both the scikit-hep and the PDG API source. A missing spatial parity becomes Parity.UNKNOWN, since every particle has one. A missing C-parity or G-parity becomes Parity.UNKNOWN only if the quantum numbers show that it exists (self-conjugate particles for C, flavorless mesons with isospin for G) and stays None otherwise. For example, K+ keeps c_parity=None, while Z0 gets parity=Parity.UNKNOWN.
  • Edge property labels render an unknown parity as ?.

❗ Behavioral changes

Important

Particles with an unknown parity can now appear in solutions.

Previously, an unknown parity was stored as None, which parity_conservation treated as a violation and which never matched an intermediate state in the solver. As a result, particles like Z0, W±, D(s)*±, and several Xi/Omega resonances (24 of the 542 default particles) were silently excluded from any reaction where parity conservation applies.

  1. Intermediate state matching: an unknown parity matches any defined parity value the solver assigns (±1), but not None, so these particles can be selected as resonances.
  2. Conservation rules: parity_conservation, parity_conservation_helicity, c_parity_conservation, and g_parity_conservation treat Parity.UNKNOWN as cannot be checked and let it pass instead of rejecting it. The C-parity and G-parity rules still apply the particle-antiparticle pair formulas, which do not depend on the individual parities. None keeps its meaning of not defined for C-parity and G-parity.

Expect additional solutions in reactions involving these particles. Both parity rules now also handle a missing spatial parity consistently: before, parity_conservation rejected None while parity_conservation_helicity ignored it. Note that g, Z0, and H0 get c_parity=Parity.UNKNOWN, although C-parity is physically not defined for the gluon and the Z0, because the particle databases do not distinguish these cases.

Squash commit messages

* BEHAVIOR: allow particles with unknown parity in solutions
* ENH: distinguish unknown from undefined parities in particle adapters

@Flomber Flomber added the ✨ Feature New feature added to the package label Nov 17, 2026
@Flomber Flomber self-assigned this Nov 17, 2026
@Flomber

Flomber commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

Behavior change: I changed the behavior of the Parity.UNKNOWN so that particles with an unknown parity can now appear in solutions.

Previously, an unknown parity was stored as None, which parity_conservation treated as a violation and which never matched an intermediate state in the solver. As a result, particles like Z0, W±, D(s)*±, and several Xi/Omega resonances (24 of the 542 default particles) were silently excluded from any reaction where parity conservation applies.

Now with Parity.UNKNOWN:

  1. Intermediate state matching: an unknown parity matches any parity value the solver assigns (±1), so these particles can be selected as resonances.
  2. Conservation rules: parity, C-parity, and G-parity rules treat Parity.UNKNOWN as cannot be checked and let it pass, instead of rejecting it. None keeps its meaning of not defined (C/G-parity only) and is handled as before.

@Flomber

Flomber commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

g_parity_conservation does not detect violations in 2→1 transitions when not all G-parities are defined. The isobar check takes the G-parity of the single state from ingoing_edge_qns[0] instead of single_state:

single_state_g_parity = ingoing_edge_qns[0].g_parity  # should be single_state.g_parity

In the (2, 1) case, ingoing_edge_qns[0] is one of the two pair particles. If it has no G-parity, the rule always passes:

K = lambda pid: GParityEdgeInput(isospin_magnitude=1/2, spin_magnitude=0, pid=pid)
f0 = GParityEdgeInput(isospin_magnitude=0, spin_magnitude=0, pid=9010221, g_parity=+1)
node = GParityNodeInput(l_magnitude=1, s_magnitude=0)

g_parity_conservation([f0], [K(321), K(-321)], node)  # False ✓
g_parity_conservation([K(321), K(-321)], [f0], node)  # True ✗ should be False

This only affects topologies with two initial states.

@Flomber Flomber added ❗ Behavior Changes that may affect the framework output ⚙️ Enhancement Improvements and optimizations of existing features labels Nov 17, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

❗ Behavior Changes that may affect the framework output ⚙️ Enhancement Improvements and optimizations of existing features ✨ Feature New feature added to the package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Introduce "Unknown" state for Parity

1 participant